'\"macro stdmacro
.\"
.\" Copyright (c) 2020,2024 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMSEARCH 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmsearch\f1 \- help text and names search for metrics, instances and instance domains
.SH SYNOPSIS
\fBpmsearch\fR
[\fB\-CdinqsStTV?\fR]
[\fB\-c\fR \fIconfig\fR]
[\f3\-D\f1 \f2debug\f1]
[\fB\-h\fR \fIhost\fR]
[\fB\-p\fR \fIport\fR]
[\fB\-N\fR \fInumber\fR]
[\fB\-O\fR \fIoffset\fR]
[\fIquery\fR | \fIindom\fR]
.SH DESCRIPTION
.de SAMPLE
.RS 2n
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..
.B pmsearch
performs full text search queries to find metrics using names
and help text from metrics, instance domains and instances.
.PP
It makes use of capabilities of the Performance Co-Pilot (PCP)
.BR pmproxy (1)
service, the Valkey distributed key-value store and associated
ValkeySearch module.
.PP
Note that in order to use these services, it is
.B mandatory
that
.B pmproxy
is communicating with a Valkey key-value server
that has the
.I valkey-search.so
module loaded.
When configured to do so,
.B pmproxy
will then automatically index PCP metric names, instance names,
metric and instance domain help text into the ValkeySearch store,
from PCP archives that it discovers locally.
Refer to
.BR pmlogger (1)
and
.BR pmlogger_daily (1)
for further details.
.PP
By default
.B pmsearch
communicates with a local key-value server
however the \fB\-h\fR and \fB\-p\fR options can be used to
specify an alternate Valket instance.
If this instance is a node of a Valkey cluster, all
other instances in the cluster will be discovered
and used automatically.
.SH OPTIONS
.TP 5
\fB\-c\fR \fIconfig\fR, \fB\-\-config\fR=\fIconfig\fR
Specify the
.IR config
file to use.
.TP
\fB\-C\fR, \fB\-\-no-colour\fR
No highlighting in results text.
.TP
\fB\-d\fR, \fB\-\-docid\fR
Report document ID of each search result.
Documents are identified using a unique SHA-1 hash which
is always displayed in a 40-hexdigit human readable form.
.TP
\fB\-h\fR \fIhost\fR, \fB\-\-host\fR=\fIhost\fR
Connect to the key-value server at
.IR host ,
rather than the one the localhost.
.TP
\fB\-i\fR, \fB\-\-info\fR
Report search engine internal metrics.
.TP
\fB\-n\fR, \fB\-\-indom\fR
Perform an
.IR instance
.IR domain
related entities search
.TP
\fB\-N\fR \fIN\fR, \fB\-\-number\fR=\fIN\fR
Return
.IR N ,
search results at most.
.TP
\fB\-O\fR \fIN\fR, \fB\-\-offset\fR=\fIN\fR
Paginated results from given offset.
.TP
\fB\-p\fR \fIport\fR, \fB\-\-port\fR=\fIport\fR
Connect to the key-value server at
.IR port ,
rather than the default
.BR 6379 .
.TP
\fB\-q\fR, \fB\-\-query\fR
Perform a general text search (default).
.TP
\fB\-s\fR, \fB\-\-suggest\fR
Perform a name suggestion search
.TP
\fB\-S\fR, \fB\-\-score\fR
Report score (rank) of each result.
.TP
\fB\-T\fR, \fB\-\-total\fR
Report total number of of search results.
.TP
\fB\-t\fR, \fB\-\-times\fR
Report elapsed search execution time.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version number and exit.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH EXAMPLES
.SAMPLE
$ pmsearch kernel idle
Type: metric
Name: \fBkernel\fR.all.cpu.\fBidle\fR
One line: total \fBidle\fR CPU time from /proc/stat for all CPUs

Type: metric
Name: \fBkernel\fR.all.idletime
One line: time the current \fBkernel\fR has been \fBidle\f1 since boot

Type: metric
Name: \fBkernel\f1.percpu.cpu.\fBidle\fR
InDom: 60.0
One line: percpu \fBidle\fR CPU time metric from /proc/stat
.ESAMPLE
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.PP
For environment variables affecting PCP tools, see \fBpmGetOptions\fP(3).
.SH DEBUGGING OPTIONS
The
.B \-D
or
.B \-\-debug
option enables the output of additional diagnostics on
.I stderr
to help triage problems, although the information is sometimes cryptic and
primarily intended to provide guidance for developers rather end-users.
.I debug
is a comma separated list of debugging options; use
.BR pmdbg (1)
with the
.B \-l
option to obtain
a list of the available debugging options and their meaning.
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmproxy (1),
.BR pmlogger (1)
and
.BR pmlogger_daily (1).

.\" control lines for scripts/man-spell
.\" +ok+ SHA Valkey ValkeySearch hexdigit idletime
.\" +ok+ stat {from /proc/stat}
